Tool Execution

BindAI tools are Python functions wrapped by the @tool decorator. When an agent decides to use a tool, BindAI looks up the registered tool and executes the underlying Python function with the arguments supplied to it. The current tool execution model is intentionally simple and predictable.

How Tool Execution Works

The basic execution flow is:

User
  |
  v
Agent
  |
  v
Language Model
  |
  v
Tool Request
  |
  v
Tool Registry
  |
  v
Tool Executor
  |
  v
Python Function
  |
  v
ToolResult
  |
  v
Agent
  |
  v
Final Response

The tool registry identifies the requested tool, while the tool execution layer invokes the underlying Python function.

Creating a Tool

Create a tool by decorating a Python function with @tool.

from bindai import tool


@tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

The decorator converts the function into a BindAI Tool. The resulting tool contains the information BindAI needs to expose and execute the function.

Tool Objects

A Tool represents a callable capability. Conceptually, a tool contains:

Tool
 |
 +-- name
 |
 +-- description
 |
 +-- function

The name identifies the tool. The description explains its purpose. The function performs the actual operation. Applications normally create tools through the @tool decorator rather than constructing Tool objects manually.

Tool Names

By default, the tool name comes from the Python function name.

@tool
def get_weather(city: str): ...

The resulting tool name is:

get_weather

An explicit name can be supplied when the model-facing name should differ from the Python function name:

@tool(name="weather")
def get_weather(city: str): ...

The registered tool is then named:

weather

Explicit names can be useful when an application needs a stable or more concise tool name.

Tool Descriptions

A tool description communicates what the operation does. For example:

@tool
def get_weather(city: str):
    """Return the weather for a city."""
    ...

The description can also be provided explicitly:

@tool(
    name="weather",
    description="Return the current weather for a city.",
)
def get_weather(city: str): ...

Clear descriptions help the model understand when a tool is appropriate. Avoid vague descriptions such as:

Do something.

Prefer descriptions that identify the operation and its purpose.

Registering a Tool

Tools can be registered directly on an agent.

agent.tool(get_weather)

Tools can also be registered during agent construction.

from bindai import Agent

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("Use available tools when appropriate.")
    .tool(get_weather)
    .build()
)

Multiple tools can be registered together:

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(
        get_weather,
        search,
        calculate,
    )
    .build()
)

The Tool Registry

Registered tools are stored in a ToolRegistry. The registry is responsible for finding a tool by name. Conceptually:

Tool Name
    |
    v
ToolRegistry
    |
    v
Tool

When a tool name is requested, the registry identifies the corresponding Tool. This allows the execution layer to work with tools by their registered names rather than depending directly on a particular Python function.

Tool Executor

BindAI uses a ToolExecutor to execute registered tools. The executor works with a ToolRegistry and resolves the requested tool before invoking it. Conceptually:

ToolExecutor
     |
     v
ToolRegistry
     |
     v
Tool
     |
     v
Python Function

The execution layer is responsible for coordinating the lookup and invocation of the registered tool.

What Happens During Execution?

The execution process can be represented as:

Requested Tool Name
        |
        v
Look up ToolRegistry
        |
        +-- Tool found ------> Execute function
        |                           |
        |                           v
        |                       ToolResult
        |
        +-- Tool missing ----> Failed ToolResult

A missing tool should not result in an arbitrary Python function being executed. The registry provides the boundary between a requested tool name and an actual registered callable.

Tool Arguments

Arguments are passed to the underlying Python function according to its signature. For example:

@tool
def add(a: int, b: int) -> int:
    return a + b

The underlying function can receive positional arguments:

add(10, 20)

or keyword arguments:

add(a=10, b=20)

The function signature defines which arguments are expected. Keep tool signatures explicit and easy to understand.

Tool Results

Tool execution produces a ToolResult. A successful result conceptually contains:

success = True
output  = <tool output>
error   = None

A failed result can contain an error instead:

success = False
output  = None
error   = <error information>

The result provides a consistent representation of the outcome of tool execution. Applications should distinguish successful tool output from tool execution failures.

Unknown Tools

If execution receives a tool name that is not registered, the execution layer should not attempt to call an unrelated function. The result represents the failed tool lookup. Conceptually:

Requested:
    unknown_tool

Registry:
    Tool not found

Result:
    failure

This protects the execution path from invalid tool names.

Tool Errors

The executor ultimately delegates the operation to the registered tool. Tools can handle expected application-level failures themselves. For example:

from bindai import tool


@tool
def divide(a: float, b: float):
    """Divide one number by another."""
    if b == 0:
        return "Division by zero is not allowed."

    return a / b

For external services, database operations, and other integrations, handle expected operational failures appropriately. Keep error information useful without exposing unnecessary internal details.

Exceptions

Not every exception should be converted into a normal tool result. Unexpected programming errors should generally remain visible during development so they can be diagnosed and fixed. Expected operational failures may be handled explicitly. For example:

@tool
def read_file(path: str) -> str:
    """Read a text file."""
    try:
        with open(path, encoding="utf-8") as file:
            return file.read()
    except FileNotFoundError:
        return "File not found."

The appropriate strategy depends on the application. Do not silently hide programming errors that should be fixed in the tool implementation.

Tool Context

The current BindAI tool API does not require an implicit ExecutionContext or context.variables object for standard tool execution. Instead, tools should receive the information they need through explicit function parameters. For example:

@tool
def get_customer(customer_id: int): ...

This makes the tool contract explicit. It also makes the function easier to test independently from an agent execution.

Passing Application State

If a tool needs application-specific state, pass the required information explicitly when that state is part of the tool’s public input. For example:

@tool
def create_report(
    customer_id: int,
    format: str,
): ...

The tool now clearly communicates which values it needs. For more advanced dependency-management requirements, use normal Python application patterns or the specific API provided by the relevant BindAI component. Do not rely on undocumented global state or implicit context variables.

Avoid Global State

Avoid storing request-specific information in global variables. Avoid:

CURRENT_CUSTOMER = None

Prefer explicit parameters:

@tool
def get_customer(customer_id: int): ...

Explicit inputs make tools easier to:

Test
Reuse
Debug
Reason about
Execute safely

Tool Execution and Workflows

Tools can be used as part of larger application workflows. A workflow can provide the values required by a tool and use the resulting tool output in later processing. The important distinction is:

Tool parameters represent inputs required by the function.
Tool output / ToolResult represents the result of execution.
Workflow state belongs to the workflow implementation.
Agent execution state should not be assumed to be an implicit tool context.

This separation keeps the boundaries between tools and workflows clear.

Tool Lifecycle

A complete tool lifecycle is:

Define Function
      |
      v
@tool Decorator
      |
      v
Tool Object
      |
      v
Register Tool
      |
      v
ToolRegistry
      |
      v
Tool Execution
      |
      v
Python Function
      |
      v
ToolResult

When the tool is used as part of an agent request, the model can receive the resulting tool output and continue the agent execution.

Tool Execution and the Agent

The agent coordinates model interaction and tool execution. Conceptually:

                 Agent
                   |
          +--------+--------+
          |                 |
          v                 v
    Model Provider       Tools
          |                 |
          v                 v
      Tool Request      Tool Execution
          |                 |
          +--------+--------+
                   |
                   v
              Final Result

The model decides when a registered capability is useful. BindAI then executes the selected tool and makes its result available to the ongoing agent execution.

Tool Execution and Providers

Tool execution is separated from the specific language model provider. Conceptually:

                 BindAI Agent
                      |
                      v
                Model Provider
                      |
                      v
                  Tool Call
                      |
                      v
                BindAI Tool
                      |
                      v
               Python / API

This separation allows the same application-level tool implementations to be used with different supported providers. The provider handles the model-facing representation of tool calls while BindAI handles application-level tool execution.

Tool Context vs Explicit Inputs

Prefer explicit inputs when the value is genuinely part of the tool’s operation. For example:

@tool
def send_notification(
    user_id: int,
    message: str,
): ...

This is easier to understand than relying on hidden state such as:

current_user
current_message
current_request

Explicit parameters also make unit tests straightforward.

Tool Context and Security

Explicit inputs do not remove the need for authorization. For example:

@tool
def delete_document(document_id: str): ...

The fact that document_id is supplied explicitly does not mean the requested operation should automatically be allowed. The application should still verify:

Authentication
Authorization
Resource ownership
Input validity
Operation scope

The model should never be treated as a security boundary.

Tool Execution with External Services

When a tool communicates with an external service, keep the external-service logic isolated where practical. For example:

Agent
  |
  v
Tool
  |
  v
Connection / Client
  |
  v
External Service

The tool can expose a focused operation while a dedicated client or BindAI connection handles communication details. This approach makes the tool easier to test and keeps external-service concerns separate from agent behavior.

Tool Execution with Memory

Tools can operate alongside BindAI memory. For example:

Agent
  |
  +---- Memory
  |
  +---- Tool
  |
  v
Execution

Memory provides contextual information to the agent. The tool performs an operation. These are separate capabilities and should not be confused with one another. If a tool needs information from application state, pass that information through an explicit interface rather than assuming that memory automatically becomes tool context.

Tool Execution with Knowledge

Tools can also operate alongside BindAI knowledge and retrieval. For example:

Agent
  |
  +---- Knowledge / Retrieval
  |
  +---- Search Tool
  |
  +---- External API Tool
  |
  v
Response

Knowledge and retrieval are primarily concerned with finding relevant information. Tools are concerned with executing operations. An application can use both mechanisms in the same agent.

Tool Execution with Multi-Agent Systems

Different agents can have different tool sets. For example:

                 Team
                  |
        +---------+---------+
        |         |         |
        v         v         v
    Research    Support   Operations
       |           |         |
    Search       CRM       APIs
    Tools        Tools     Tools

This allows specialist agents to expose only the capabilities relevant to their roles. Focused tool sets can make multi-agent systems easier to reason about and safer to operate.

Testing Tool Execution

Tool execution should be tested independently from the language model whenever possible. For example, test the underlying operation directly:

def multiply(a: int, b: int) -> int:
    return a * b


assert multiply(2, 3) == 6

Then test the BindAI integration separately. Useful test areas include:

Tool creation
Tool registration
Tool lookup
Positional arguments
Keyword arguments
Successful execution
Unknown tools
Tool failures
Multiple registered tools
Security and authorization boundaries

This separation makes failures easier to diagnose.

Complete Example

from bindai import Agent, tool


@tool(
    name="multiply",
    description="Multiply two integers.",
)
def multiply(
    a: int,
    b: int,
) -> int:
    return a * b


agent = (
    Agent.builder()
    .name("calculator")
    .model("openai:gpt-4.1-mini")
    .instructions("Use the multiply tool when arithmetic is required.")
    .tool(multiply)
    .build()
)

result = agent.run("What is 14 × 9?")

if result.success:
    print(result.output)
else:
    print(result.error)

The tool is registered with the agent and becomes available during agent execution. The model can request the tool when appropriate, BindAI executes the underlying Python function, and the resulting tool output is returned to the ongoing execution.

Best Practices

Use explicit function parameters for tool inputs.
Add Python type hints.
Give tools clear names.
Write concise descriptions.
Use docstrings when appropriate.
Keep tools focused on one responsibility.
Avoid request-specific global state.
Handle expected application failures clearly.
Keep tool outputs predictable.
Validate inputs before performing external operations.
Keep authorization in application code.
Do not expose credentials through tool parameters or results.
Do not depend on undocumented execution-context APIs.
Test tool functions independently from language-model execution.
Use dedicated connections for reusable external integrations.
Use workflows for complex orchestration.

Summary

BindAI’s current tool execution model is intentionally straightforward. A Python function is converted into a Tool using @tool, registered with an agent, resolved through the tool registry, and executed as part of agent execution. The underlying Python function receives the arguments defined by its signature, and the execution system represents the outcome through tool-result handling. For standard tools, inputs should be explicit rather than relying on an implicit ExecutionContext or context.variables abstraction. This design keeps tools:

Explicit
Testable
Reusable
Provider-independent
Easier to secure

Tools therefore provide a clear boundary between model-driven tool selection and trusted application code.

​Tool Execution

​How Tool Execution Works

​Creating a Tool

​Tool Objects

​Tool Names

​Tool Descriptions

​Registering a Tool

​The Tool Registry

​Tool Executor

​What Happens During Execution?

​Tool Arguments

​Tool Results

​Unknown Tools

​Tool Errors

​Exceptions

​Tool Context

​Passing Application State

​Avoid Global State

​Tool Execution and Workflows

​Tool Lifecycle

​Tool Execution and the Agent

​Tool Execution and Providers

​Tool Context vs Explicit Inputs

​Tool Context and Security

​Tool Execution with External Services

​Tool Execution with Memory

​Tool Execution with Knowledge

​Tool Execution with Multi-Agent Systems

​Testing Tool Execution

​Complete Example

​Best Practices

​Summary